<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>LibDeflate documentation</title>
    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>LibDeflate</h1>

<ul>
  <li><a href="../index.html">Index</a></li>
</ul>



<h2>Examples</h2>
<ul class="nowrap">
  <li><strong>example.lua</strong></li>
</ul>
<h2>Topics</h2>
<ul class="">
  <li><a href="../topics/README.md.html">README</a></li>
  <li><a href="../topics/benchmark.md.html">benchmark</a></li>
  <li><a href="../topics/changelog.md.html">changelog</a></li>
</ul>
<h2>Source</h2>
<ul class="nowrap">
  <li><a href="../source/LibDeflate.lua.html">LibDeflate.lua</a></li>
</ul>

</div>

<div id="content">

    <h2>example.lua</h2>
<pre>
<span class="comment">--[[
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see https://www.gnu.org/licenses/.
--]]</span>

<span class="comment">--- LibDeflate usage example
</span><span class="comment">-- @author Haoqian He
</span><span class="comment">-- @file example.lua
</span>
<span class="keyword">local</span> LibDeflate

<span class="keyword">if</span> LibStub <span class="keyword">then</span> <span class="comment">-- You are using LibDeflate as WoW addon
</span>	LibDeflate = LibStub:GetLibrary(<span class="string">"LibDeflate"</span>)
<span class="keyword">else</span>
	<span class="comment">-- You are using LibDeflate as Lua library.
</span>	<span class="comment">-- Setup the path to locate LibDeflate.lua,
</span>	<span class="comment">-- if 'require("LibDeflate")' fails, for example:
</span>	<span class="comment">-- package.path = ("?.lua;../?.lua;")..(package.path or "")
</span>	LibDeflate = <span class="global">require</span>(<span class="string">"LibDeflate"</span>)
<span class="keyword">end</span>

<span class="keyword">local</span> example_input = <span class="string">"12123123412345123456123456712345678123456789"</span>

<span class="comment">-- Compress using raw deflate format
</span><span class="keyword">local</span> compress_deflate = LibDeflate:CompressDeflate(example_input)

<span class="comment">-- decompress
</span><span class="keyword">local</span> decompress_deflate = LibDeflate:DecompressDeflate(compress_deflate)
<span class="comment">-- Check if the first return value of DecompressXXXX is non-nil to know if the
</span><span class="comment">-- decompression succeeds.
</span><span class="keyword">if</span> decompress_deflate == <span class="keyword">nil</span> <span class="keyword">then</span>
	<span class="global">error</span>(<span class="string">"Decompression fails."</span>)
<span class="keyword">else</span>
	<span class="comment">-- Decompression succeeds.
</span>	<span class="global">assert</span>(example_input == decompress_deflate)
<span class="keyword">end</span>


<span class="comment">-- If it is to transmit through WoW addon channel,
</span><span class="comment">-- compressed data must be encoded so NULL ("\000") is not transmitted.
</span><span class="keyword">local</span> data_to_trasmit_WoW_addon = LibDeflate:EncodeForWoWAddonChannel(
	compress_deflate)
<span class="comment">-- When the receiver gets the data, decoded it first.
</span><span class="keyword">local</span> data_decoded_WoW_addon = LibDeflate:DecodeForWoWAddonChannel(
	data_to_trasmit_WoW_addon)
<span class="comment">-- Then decomrpess it
</span><span class="global">assert</span>(LibDeflate:DecompressDeflate(data_decoded_WoW_addon) == example_input)

<span class="comment">-- The compressed output is not printable. EncodeForPrint will convert to
</span><span class="comment">-- a printable format, in case you want to export to the user to
</span><span class="comment">-- copy and paste. This encoding will make the data 25% bigger.
</span><span class="keyword">local</span> printable_compressed = LibDeflate:EncodeForPrint(compress_deflate)

<span class="comment">-- DecodeForPrint to convert back.
</span><span class="comment">-- DecodeForPrint will remove prefixed and trailing control or space characters
</span><span class="comment">-- in the string before decode it.
</span><span class="global">assert</span>(LibDeflate:DecodeForPrint(printable_compressed) == compress_deflate)


<span class="comment">-------------------------------------------------------------------------------
</span><span class="comment">-------------------------------------------------------------------------------
</span><span class="comment">-------------------------------------------------------------------------------
</span>
<span class="comment">--- Compress and decompress using zlib format
</span><span class="keyword">local</span> compress_zlib = LibDeflate:CompressZlib(example_input)
<span class="keyword">local</span> decompress_zlib = LibDeflate:DecompressZlib(compress_zlib)
<span class="global">assert</span>(decompress_zlib == example_input)

<span class="comment">--- Control the compression level
</span><span class="comment">-- NOTE: High compression level does not make a difference here,
</span><span class="comment">-- because the input data is very small
</span><span class="keyword">local</span> compress_deflate_with_level = LibDeflate:CompressDeflate(example_input
	, {level = <span class="number">9</span>})
<span class="keyword">local</span> decompress_deflate_with_level = LibDeflate:DecompressDeflate(
	compress_deflate_with_level)
<span class="global">assert</span>(decompress_deflate_with_level == example_input)


<span class="comment">-- Compress with a preset dictionary
</span><span class="keyword">local</span> dict_str = <span class="string">"121231234"</span> <span class="comment">-- example preset dictionary string.
</span><span class="comment">-- print(LibDeflate:Adler32(dict_str), #dict_str)
</span><span class="comment">-- 9 147325380
</span><span class="comment">-- hardcode the print result above, the ensure it is not modified
</span><span class="comment">-- accidenttaly during the program development.
</span><span class="comment">--
</span><span class="comment">-- WARNING: The compressor and decompressor must use the same dictionary.
</span><span class="comment">-- You should be aware of this when tranmitting compressed data over the
</span><span class="comment">-- internet.
</span><span class="keyword">local</span> dict = LibDeflate:CreateDictionary(dict_str, <span class="number">9</span>, <span class="number">147325380</span>)

<span class="comment">-- Using the dictionary with raw deflate format
</span><span class="keyword">local</span> compress_deflate_with_dict = LibDeflate:CompressDeflateWithDict(
	example_input, dict)
<span class="global">assert</span>(#compress_deflate_with_dict &lt; #compress_deflate)
<span class="keyword">local</span> decompress_deflate_with_dict = LibDeflate:DecompressDeflateWithDict(
	compress_deflate_with_dict, dict)
<span class="global">assert</span>(decompress_deflate_with_dict == example_input)

<span class="comment">-- Using the dictionary with zlib format, specifying compression level
</span><span class="keyword">local</span> compress_zlib_with_dict = LibDeflate:CompressZlibWithDict(
	example_input, dict, {level = <span class="number">9</span>})
<span class="global">assert</span>(#compress_zlib_with_dict &lt; #compress_zlib)
<span class="keyword">local</span> decompress_zlib_with_dict = LibDeflate:DecompressZlibWithDict(
	compress_zlib_with_dict, dict)
<span class="global">assert</span>(decompress_zlib_with_dict == example_input)</pre>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-06-26 22:05:55 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
